Quarto for the curious


Tom Mock, RStudio PBC

 rstd.io/quarto-curious

2022-07-27

We don’t talk about Quarto

We don’t talk about Quarto

We don’t talk about Quarto

A tweet by Alison Hill revealing her blogpost on Quarto. Over the weekend, I wrote up my notes about using and teaching Quarto, based on my experiences  working with the development team for over a year. I think (hope?) it is safe to talk about it now

We don’t talk about Quarto

A tweet by Kelly Bodwin revealing her excitement about Quarto. Did I stay up until 6am before the first night of class converting all my R Markdown materials to @quarto_dev? Yes, yes I did. Do I regret it? No, I do not. It's pretty rad my dudes.

We don’t talk about Quarto

We don’t talk about Quarto

Others had more questions…

What is a “Quarto”?

What is a “Quarto”?1

Ok, but what IS Quarto®?

Ok, but what IS Quarto®?

Quarto® is an open-source scientific and technical publishing system built on Pandoc

Pandoc is a “swiss army knife” for converting simple documents into other formats

Quarto extends Pandoc with heavy use of pre-processing with Lua filters

function Strong(elem)
  return pandoc.SmallCaps(elem.c)
end

and provides a native publishing workflow

quarto publish document.qmd     

How do I make a cocktail?

Image: Kobby Mendez

Crafting a cocktail

diagram of converting liquor, citrus, sugar into delicious cocktails

“Crafting” process for literate programming

“Crafting” process for literate programming

“Crafting” process for literate programming

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

diagram of converting a Jupyter notebook via pandoc into markdown and then into output formats

So what is a .qmd?

A Quarto document i.e. a .qmd is a plain text file, like a .rmd, that can be rendered to many different formats

A screenshot of a Visual and Source Quarto document

Anatomy of a Quarto document

  • Metadata (YAML)
format: html
engine: knitr
engine: jupyter #< for native Python/Julia without requiring R
  • Code
```{r cars}
#| eval: false
mtcars |> 
  dplyr::group_by(cyl) |> 
  dplyr::summarize(mean = mean(mpg), .groups = "drop")
```
  • Text
# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

So what is Quarto?

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into PDF/Word/HTML reports, books, websites, presentations and more!

A screenshot of a Visual and Source Quarto document

So what is Quarto?



Quarto is the next-generation of RMarkdown.

For everyone.

One install, batteries included

One install, “Batteries included”

  • Any language, same syntax and approach
Feature R Markdown Quarto
Basic Formats
Beamer
PowerPoint
HTML Slides
Advanced Layout

Many Quarto formats

Feature R Markdown Quarto
Cross References
Websites & Blogs
Books
Interactivity Shiny Documents Quarto Interactive Documents
Paged HTML pagedown Summer 2022
Journal Articles rticles Summer 2022
Dashboards flexdashboard Fall 2022

Built-in tabsets

```{r penguin-sum}
#| eval: false
library(dplyr, warn.conflicts=FALSE)
penguin_sum <- palmerpenguins::penguins |>
  group_by(species, sex) |>
  summarize(
    n = n(),
    across(
      c(body_mass_g, bill_length_mm, flipper_length_mm),
      list(
        mean = ~ mean(.x, na.rm = TRUE), 
        sd = ~ sd(.x, na.rm = TRUE)
      )
    ),
  )

penguin_sum
```
# A tibble: 8 × 9
# Groups:   species [3]
  species   sex        n body_mass_g_mean body_mass_g_sd bill_length_mm_mean
  <fct>     <fct>  <int>            <dbl>          <dbl>               <dbl>
1 Adelie    female    73            3369.           269.                37.3
2 Adelie    male      73            4043.           347.                40.4
3 Adelie    <NA>       6            3540            477.                37.8
4 Chinstrap female    34            3527.           285.                46.6
5 Chinstrap male      34            3939.           362.                51.1
6 Gentoo    female    58            4680.           282.                45.6
7 Gentoo    male      61            5485.           313.                49.5
8 Gentoo    <NA>       5            4588.           338.                45.6
# … with 3 more variables: bill_length_mm_sd <dbl>,
#   flipper_length_mm_mean <dbl>, flipper_length_mm_sd <dbl>

Figure Layout

::: {layout-nrow=2}
![Surus](surus.png)

![Hanno](hanno.png)

![Abdul Abbas](abdul-abbas.png)

![Lin Wang](lin-wang.png)
:::

Interactivity

  • Quarto supports {htmlwidgets} and {shiny} in R or Jupyter Widgets for Python.

Quarto also includes native support for Observable JS, a set of enhancements to vanilla JavaScript created by Mike Bostock (also the author of D3)

Next-Gen RMarkdown, unification

We learned from 10 years of literate programming with knitr + rmarkdown - Quarto is the continuation and unification of the best parts of RMarkdown via knitr.

RMarkdown and knitr are not going away, we’re still supporting it!

diagram of converting a Quarto document via knitr/pandoc into markdown and then into output formats

Next-Gen RMarkdown, extended for everyone

I feel as if R Markdown’s birth certificate had a letter “R” stamped on it, and Jupyter had a “Python” stamp - Yihui Xie (author of knitr) 1

The main technical difference between Quarto and R Markdown is that Quarto makes heavy use of Pandoc’s Lua filters. - Yihui Xie 2

We are meeting Julia/Python users in their native language

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

Collaboration between multi-lingual teams

1

Photo by zero take

roam in color

Comfort of your own workspace

Comfort of your own workspace

A screenshot of a Quarto document rendered inside RStudio

A screenshot of a Quarto document rendered inside JupyterLab

A screenshot of a Quarto document rendered inside VSCode

What to do with my existing .Rmd or .ipynb?

RMarkdown (and knitr) is not going away!

For some of you - nothing changes! Keep using RMarkdown and Jupyter.

However, most existing .rmd or .ipynb can be rendered as-is via Quarto or with some editing. Quarto comes out of the box with better accessibility, better defaults, more options, and a more consistent syntax.

quarto render my-favorite.rmd --to html


Since Jupyter notebooks can either be treated as a linear document to be re-executed or output document there are additional options like: --execute

quarto render my-favorite.ipynb --to html --execute

What to do with my existing .Rmd or .ipynb?

In fact, Quarto can help convert back and forth between .qmd and .ipynb:

quarto convert --help

Usage:   quarto convert <input>

Description:

    Convert documents to alternate representations.

  Convert notebook to markdown:                  quarto convert mydocument.ipynb                   
  Convert markdown to notebook:                  quarto convert mydocument.qmd                     
  Convert notebook to markdown, writing to file: quarto convert mydocument.ipynb --output mydoc.qmd

Quarto Publish

quarto publish --help

  Usage:   quarto publish [provider] [path]
  Version: 1.0.0                          
                                           
  Description:
    Publish a document or project. Available providers include:
                                                               
     - Quarto Pub (quarto-pub)                                 
     - GitHub Pages (gh-pages)                                 
     - RStudio Connect (connect)                               
     - Netlify (netlify)                                       
     
    Accounts are configured interactively during publishing.   
    Manage/remove accounts with: quarto publish accounts 

What about for Data Science at Work?

  • Quarto can be used in the latest version of RStudio Team today!

Cocktails vs Mixed Drinks

Quarto, crafted with love and care

Development of Quarto is sponsored by RStudio, PBC. The same core team works on both Quarto and R Markdown:

Here is the full contributors list. Quarto is open source and we welcome contributions in our github repository as well! https://github.com/quarto-dev/quarto-cli.

Quarto

  • Batteries included, shared syntax across output types and languages
  • Choose your own editor and your preferred data science language
  • More enhancements overtime - RMarkdown still maintained, but majority of new features built into Quarto

Follow @quarto_pub or me @thomas_mock on Twitter to stay up to date!